tree-changes

What is tree-changes?

The tree-changes npm package is a utility for detecting changes between two states of a JavaScript object. It helps in identifying added, updated, and removed properties, making it useful for state management and change detection in applications.

What are tree-changes's main functionalities?

Detect Added Properties

This feature allows you to detect properties that have been added to the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1 };
const nextState = { a: 1, b: 2 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.added()); // { b: 2 }

Detect Updated Properties

This feature allows you to detect properties that have been updated in the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1 };
const nextState = { a: 2 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.updated()); // { a: 2 }

Detect Removed Properties

This feature allows you to detect properties that have been removed from the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1, b: 2 };
const nextState = { a: 1 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.removed()); // { b: 2 }

Other packages similar to tree-changes

deep-diff

The deep-diff package provides a way to find the differences between two JavaScript objects. It supports nested objects and arrays, making it more versatile for complex data structures. Compared to tree-changes, deep-diff offers more granular control over the types of differences detected, such as additions, deletions, and modifications.

diff

The diff package is a general-purpose text and object diffing library. It can be used to compare strings, arrays, and objects, and provides detailed information about the differences. While it is more comprehensive than tree-changes, it may be overkill for simple state change detection.

immutability-helper

The immutability-helper package is designed to help with updating immutable data structures. It provides a set of commands to apply changes to an object without mutating it. While it doesn't directly compare states like tree-changes, it is useful for managing state updates in a predictable way.

README

tree-changes

Get changes between two versions of the same object.
A good use for this is in React lifecycle methods, like componentWillReceiveProps or componentDidUpdate.

Setup

npm install tree-changes

Usage

import treeChanges from 'tree-changes';

const A = {
    status: 'idle',
    hasData: false,
    data: { a: 1 },
    items: [{ name: 'test' }],
    ratio: 0.45,
    retries: 0,
    switch: false,
};

const B = {
    status: 'done',
    hasData: true,
    data: { a: 1 },
    items: [],
    ratio: 0.4,
    retries: 1,
};

const { changed, changedFrom, changedTo, increased, decreased } = treeChanges(objA, objB);

if (changed('status')) {
    // do something
}

if (changedFrom('retries', 0, 1) {
    // should we try again?
}

// works with array values too
if (changedFrom('status', 'idle', ['done', 'ready']) {
    // status has changed!
}

if (decreased('ratio')) {
    // hey, slow down.
}

With React

import treeChanges from 'tree-changes';

class Comp extends React.Component {
    ...
    componentDidUpdate(prevProps) {
        const { changedFrom, changedTo } = treeChanges(prevProps, this.props);
        
        if (changedFrom('retries', 0, 1) {
            // dispatch some error
        }
        
        if (changedTo('hasData', true)) {
            // send data to analytics or something.
        }
    }
    ...
}

API

changed(key: string)
Check if the value has changed. Supports objects and arrays.

changedFrom(key: string, previous: string | boolean | number, actual: string | boolean | number)
Check if the value has changed from previous to actual.

changedTo(key: string, actual: string | boolean | number)
Check if the value has changed to actual.

increased(key: string)
Check if both versions are numbers and the value has increased.

decreased(key: string)
Check if both versions are numbers and the value has decreased.